Short:    make MPEGs with ImageFX
Type:     gfx/conv
Author:   mlelstv@serpens.rhein.de
Uploader: mlelstv@serpens.rhein.de

Hello,

this is my first try to create MPEGs comfortably with ImageFX.
I am using a modified PVRG MPEG codec, the program can now read
input from pipes and can communicate with an AREXX function host
to provide input data.

The BuildMPEG.ifx script works as follows:

Here for some legal stuff:
 *  Copyright Michael van Elst 1994
 *
 *  This program is freely distributable, but copyrighted by me. This means
 *  that you can copy it freely as long as you don't ask for any more money
 *  than a nominal fee for copying. This program may be put on PD disks,
 *  especially on Fred Fish's AmigaLibDisks.
 *  This program cannot be used for commercial purposes without permission
 *  from the author. The author can not be made responsible for any damage
 *  which is caused by using this program.
 *  
 *  This notice applies to the AREXX script, my changes to the MPEG codec
 *  done by the Portable Video Research Group at Stanford and the resulting
 *  executable contained in the BuildMPEG archive.

- query parameters from user

  - 'input pattern' denotes the filenames of the input frames
	you can use any picture file format that ImageFX is able to
	load but no ANIM files yet. The pattern is of the form
	prefix%suffix where the the % gets replaced by the frame
	number starting with the 'From' value up to the 'To' value.
	You can use a sequence of % characters to produce a minimal
	number of digits. Say micky.%%%.iff would yield micky.001.iff,
	micky.002.iff,... Lightwave would use a pattern like picture%%%.

  - 'output filename' is of course the pathname for the generated
	MPEG stream

  - Frame Interval is the distance between the intracoded and predicted
	frames
  - Group Interval is the number of frame intervals in a group
	Both values control the number of generated predicted and interpolated
	frames. The default values of 3 and 2 will generate a pattern like:
	I,B,B,P,B,B,I,B,B,P,B,B...

  - Frame Rate tells the encoder what nominal play back speed the stream
	is used for. The MPEG committee agreed on a couple of possible speeds
	often found in video. The encoder will use this value for rate control
	and a possible (hardware) decoder would use that value to set the play
	back speed.

  - Bitrate (in kbits/s) tells the Encoder the data transfer speed of the
	target device and is used together with the frame rate for rate
	control. 1200 is the value for CD-ROMs (1200kbit/s = 150kbyte/s).

  - Targetsize is the approximate size of the output file. The encoder will
	try to not exceed that file size. The Targetsize option overrides
	the Bitrate option.

  - XING Override. Tell the encoder to produce XING compatible MPEG streams.
	This puts certain limitations on the stream, like 160x120 frame size.
	It will also turn of motion estimation, just I frames are produced.
	If source frames aren't already XING sized they will be _scaled_
	accordingly but aspect ratio is not necessarily preserved.

  - Query Advanced Options. If checked you'll get another requester where
	you can set more details of the encoding process.

- maybe more parameters for 'Advanced Options'

  - DC Intraframe mode chooses a special high compression mode where each
	8x8 block just gets its DC value encoded (i.e. average value).

  - Use Precise DCT will enable a 'reference DCT' algorithm that works
	with floating point instead of the much faster integer based
	algorithm used normally.

  - Motion Vector Telescoping. Extends the motion vector search area
	depending on the temporal distance.

  - Dynamic Motion Vector Bounding. Useful (==faster) for frames with
    limited motion vector movement but produces worse results in scenes
    with heavy motion.

  - Motion Vector Prediction.

  - Search Diameter. Area scanned for moving objects, can be very large
	(say 128). Default is 15.

  - Quantization. Initial quantization value (1..31). Rate control will
	adapt this as necessary.

  - Control script. The codec can read a script with even more details
	for the encoding process. If the script isn't specified with a
	full pathname it is searched in the directory IMAGEFX:mpegcontrol/
	For more details on the scripting language read the original Codec
	documentation.

  - IFX Filter. To adapt input sources to MPEG requirements it is possible
	to insert user specified commands after loading each frame. This string
	gadget accepts a filename or a literal AREXX command. If the filename
	is not absolute (i.e. does not contain a ':') the file is searched in
	the directory IMAGEFX:mpegfilters/. A suffix of ".ifx" is automatically
	appended if necessary.
	If the file cannot be found then the string is executed literally. This
	allows to enter trivial commands directly instead of writing a script.

- then the script detrmines the command line parameters for the codec
  and launches it with RUN

- the script listens to a an AREXX port where the codec will ask to
  feed it with new frames. The script will tell ImageFX to load these
  frames and to save the Y, U or V parts to a PIPE: where the codec
  will read the data.

- the codec tells the script to finish when all frames are processed.

The AREXX script currently stores and retrieves all the parameters
into and from the AREXX clip list which means you do not have to
reenter them until the next reboot.

Files:

mpeg          - the PVRG codec compiled for 68020+ and no FPU
doc.ps        - the original documentation from the PVRG
README        -  ""
SETUP         -  ""
YUVSPLIT.000  - ImageFX saver module compiled for 68000
YUVSPLIT.030  - ImageFX saver module compiled for 68030
BuildMPEG.ifx - AREXX control script
BuildMPEG.readme - this file :)

Saver Module:

The Saver Module might be useful elsewhere, so here a short description.

Choose YUVSPLIT as the output format. ImageFX will ask for a filename.
YUVSPLIT filenames should look like  name.Y, name.U and name.V. If you
give it such a filename it will adjust the suffix for the 3 output
files. If the filename you give it has no such extension it is treated
as a basename where the suffixes are appended.
Because of that filename mangling there is currently no check against
overwriting of existing files.

From AREXX you have more fine control.

SaveBufferAS YUVSPLIT filename [Y] [U] [V] [NOCCIR601]

Without options this acts the same way as from the ImageFX control panel.
If you give it one or more of the Y,U and V flags it will just write
these parts of the image.

The NOCCIR601 will turn off scaling of the output to CCIR601 levels.
This might be useful for a JPEG codec which wants a fully saturated
input.

The 3 files are _raw_ data, just one pure signed (UV) or unsigned (Y) byte
per pixel and no header. The U and V files are _subsampled_ which means that
every 2x2 block gets a single value. Therefore the U and V files
are just one quarter the size of the Y file.

The saver replicates the last row/line as necessary as the MPEG
codec just understands even sized pictures.

Installation:

create a directory IMAGEFX:mpeg and copy the codec binary (mpeg) into it.
copy the YUVSPLIT and YUVSPLIT.030 saver modules into IMAGEFX:modules/savers
and copy the BuildMPEG.ifx script into IMAGEFX:rexx

If you want to use filter scripts I suggest to create a IMAGEFX:mpegfilters
directory and put them there. If you want to play with codec control scripts
you need a directory IMAGEFX:mpegcontrol.

For sake of speed I compiled the saver for 68000 and 68030 respectively,
ImageFX will use the correct one for your system.
The codec is compiled for 68020 and mathieee.library

Run the script from ImageFX.

Previously I said:
"WARNING: Don't try to stop the script. There is a good chance that then
either the script or the codec will wait infinitely on some PIPE access."

This version of the script tries to solve most of the problems and in fact
I haven't got any problems anymore from stopping a script.

Hope this is enough to get it working :)

Michael van Elst
